OpenEdge Development: <br />Web Services Analyzing wrapped document literal

The Analyzer recognizes and provides special documentation support for a narrow convention of the Document/Literal SOAP format developed by Microsoft known as wrapped document literal (Wrapped Doc/Lit). A Web service operation defined according to the Wrapped Doc/Lit convention has a single request (input) parameter and single response (output) parameter. Each parameter in the operation is defined as a complex element that “wraps” one or more elements containing values of the same mode (input or output).

The Analyzer can document a 4GL procedure or function that uses the Wrapped Doc/Lit convention according to one of two possible forms:

Wrapped form

In a wrapped form, the procedure or function mirrors the Wrapped Doc/Lit convention and passes two LONGCHAR parameters, INPUT and OUTPUT, each of which contains the serialized XML data for the corresponding SOAP request or response message. Programming with this definition of the procedure or function requires that you parse the XML for both the INPUT and the OUTPUT parameter. For more information on coding with the wrapped form, see the "Programming options" section.

Unwrapped form

In an unwrapped form, the procedure or function passes individual INPUT, OUTPUT, or INPUT-OUTPUT parameters that reflect the individual data elements wrapped by the out element for these Wrapped Doc/Lit operation parameters. In this case, the Analyzer is likely to document each parameter as a Progress 4GL data type that maps to a simple XML Schema data type defined in the outer elements of the wrapped parameters. (For more information, see the "Mapping XML Schema data types to Progress 4GL data types" section.) The Analyzer can also be required to document an unwrapped parameter as a complex XML Schema data type mapped to a 4GL LONGCHAR if the definition for that parameter embedded within the complex outer element is, itself, a complex element. However in many cases, only simple data types are required to implement all of the parameters for a Wrapped Doc/Lit operation. In this case, you have no need to parse any XML in the 4GL. For more information on coding with the unwrapped form, see the "Programming options" section.

Analyzer documentation options

By default, the Analyzer documents all Wrapped Doc/Lit operations using an unwrapped form. In most cases, this is the simplest form to work with in the 4GL.

However, versions of the WSDL Analyzer prior to OpenEdge Release 10.1A document Wrapped Doc/Lit operations using only the wrapped form. So, for backward compatibility, you can tell the Analyzer to document these operations using the wrapped form by specifying the -show100style command-line option when you run the Analyzer (see the "Running the Analyzer" section).

If any operations within a port type use the Wrapped Doc/Lit convention, the Analyzer writes the following note at the top of the port type document indicating that you can rerun the Analyzer to generate the operation signatures as in OpenEdge releases prior to Release 10.1A:


NOTE: Some of the procedures documented below were documented differently in the 10.0 releases of OpenEdge. If you are maintaining web service clients written for release 10.0, or are deploying web service clients in a mixed 10.0/post-10.0 installation, re-execute this utility with the `-show100style` option.

Programming options

The Progress 4GL accepts, without restriction, both the wrapped and unwrapped forms for procedures or functions that map to Wrapped Doc/Lit operations. That is, you can use any one or both of the wrapped and unwrapped forms as overloads of a Wrapped Doc/Lit operation (as documented by the Analyzer) to program that operation in the 4GL.